home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / MATRIX04.ARJ / MATRIX.DOC < prev    next >
Text File  |  1992-05-25  |  18KB  |  481 lines
  1. /*
  2. *-----------------------------------------------------------------------------
  3. *       file:   matrix.doc
  4. *       desc:   document for matrix toolbox function calls
  5. *    by:    ko shu pui, patrick
  6. *       date:   24 may 92       v0.4
  7. *-----------------------------------------------------------------------------
  8. */
  9.  
  10. ===============================================================================
  11. 0. INTRODUCTION
  12. ===============================================================================
  13. This document only provides you the following information:
  14.  
  15.         0.1     How to create and free a matrix
  16.         0.2     Description of each matrix function call
  17.         0.3     Some hints to use this toolbox
  18.  
  19. Remember that this document will NOT describe the data structure and
  20. any technical details of the toolbox - just because this document is
  21. aimed at to be a sort-of "User's Guide" for programmers.
  22.  
  23.  
  24.  
  25.  
  26. ===============================================================================
  27. 1. OUR MATRIX OF REFERENCE
  28. ===============================================================================
  29. In order to avoid terms confusion, here is our matrix of reference
  30. (matrix A) which is of size m x n.
  31.  
  32.                           Column
  33.                 Row        0       1       2          n-1
  34.                  0    [   a0,0    a0,1    a0,2   ...  a0,n-1   ]
  35.      A =         1    [   a1,0    a1,1    a1,2   ...  a1,n-1   ]
  36.                  2    [   a2,0    a2,1    a2,2   ...  a2,n-1   ]
  37.                       [   ...     ...     ...    ...  ...      ]
  38.                  m-1  [   am-1,0  am-1,1  am-1,2 ...  am-1,n-1 ]
  39.  
  40.  
  41.  
  42. ===============================================================================
  43. 2. BASIC MATRIX OBJECT OPERATION
  44. ===============================================================================
  45. -------------------------------------------------------------------------------
  46. Function :      MATRIX mat_creat (int m, int n, int type)
  47. Synopsis :      creation of a matrix which can be used by the matrix toolbox
  48.                 functions; memory is allocated for this object; and some
  49.                 initialization is performed.
  50. Parameter:      m: number of rows
  51.                 n: number of columns
  52.                 type: matrix initialization type where
  53.  
  54.                 type=
  55.  
  56.                 UNDEFINED       do not initialize the matrix
  57.                 ZERO_MATRIX     fill zero to all matrix elements
  58.                 UNIT_MATRIX     fill a one to all matrix element ai,j
  59.                                 where i=j
  60.  
  61. Return Value:   the matrix object
  62. Example:
  63.  
  64.                 MATRIX  A;
  65.  
  66.                 /*
  67.                 * create a 15 x 15 matrix;
  68.                 * do not initialize the elements
  69.                 */
  70.                 A = mat_creat( 15, 15, UNDEFINED);
  71.  
  72.                 /*
  73.                 * put a 4 in element A(0,14) of matrix A,
  74.                 * put a 2 in element A(3,5) of matrix A
  75.                 */
  76.                 A[0][14] = 4.0;
  77.                 A[3][5] = 2.0;
  78.  
  79. See Also:       mat_free(), for Accessing a matrix, see this example.
  80. -------------------------------------------------------------------------------
  81. Function:       MATRIX mat_fill ( MATRIX A, int type )
  82. Synopsis:       initialize a matrix will a simple type
  83. Parameter:      A: the matrix object for which mat_creat() has been called
  84.                 type: matrix initialization type where
  85.  
  86.                 type=
  87.  
  88.                 UNDEFINED       do not initialize the matrix
  89.                 ZERO_MATRIX     fill zero to all matrix elements
  90.                 UNIT_MATRIX     fill a one to all matrix element ai,j
  91.                                 where i=j
  92. Return Value:   MATRIX A
  93. Example:
  94.  
  95.                 MATRIX  A;
  96.  
  97.                 ...
  98.                 /*
  99.                 * fill the matrix A will zeroes
  100.                 */
  101.                 mat_fill( A, ZERO_MATRIX );
  102.  
  103. See Also:       mat_creat()
  104. -------------------------------------------------------------------------------
  105. Function :      int mat_free ( MATRIX A )
  106. Synopsis :      free all memory occupied by the matrix object A
  107. Parameter:      A: the matrix object for which mat_creat() was called
  108. Return Value:   None
  109. Example:
  110.  
  111.                 MATRIX  A;
  112.  
  113.                 A = mat_creat(...);
  114.                 ...
  115.                 mat_free(A);
  116.  
  117. Note:           since memory may be a very scarce resource in a computer,
  118.                 as a C programmer you are advised to free up the matrix as
  119.                 soon as that matrix will not be used any more in future.
  120.  
  121. See Also:       mat_creat()
  122. -------------------------------------------------------------------------------
  123. Function:       MatCol ( A )
  124. Synopsis:       find out the number of columns of a matrix object A
  125. Parameter:      A: the matrix object for which mat_creat() was called
  126. Return Value:   number of columns
  127. Example:
  128.                 int     i;
  129.  
  130.                 ...
  131.                 i = MatCol(A);
  132.  
  133. Note:           this is a macro
  134. See Also:       MatRow()
  135. -------------------------------------------------------------------------------
  136. Function:       MatRow ( A )
  137. Synopsis:       find out the number of rows of a matrix object A
  138. Parameter:      A: the matrix object for which mat_creat() was called
  139. Return Value:   number of rows
  140. Example:
  141.                 int     i;
  142.  
  143.                 ...
  144.                 i = MatRow(A);
  145.  
  146. Note:           this is a macro
  147. See Also:       MatCol()
  148.  
  149. -------------------------------------------------------------------------------
  150. Function:       MATRIX mat_colcopy1 ( MATRIX A, MATRIX B, int j1, int j2 )
  151. Synopsis:       copy a column from a matrix A to a column at matrix B
  152. Parameter:      A, B: the matrix objects for which mat_creat() was called
  153.                 column j1 of A is copied to column j2 of B;
  154. Return Value:   MATRIX A
  155. Example:
  156.                 MATRIX  A, B;
  157.  
  158.                 A = mat_creat( 5, 4, ZERO_MATRIX );
  159.                 B = mat_creat( 5, 4, UNDEFINED );
  160.  
  161.                 /*
  162.                 * copy column 2 of A to column 0 of B
  163.                 */
  164.                 mat_colcopy1( A, 2, B, 0 );
  165.  
  166. Note:           the sizes of rows of A, B must be the same
  167. See Also:       mat_copy()
  168. -------------------------------------------------------------------------------
  169. Function:       MATRIX mat_copy ( MATRIX A )
  170. Synopsis:       duplicate a matrix
  171. Parameter:      A: the matrix object for which mat_creat() was called
  172. Return Value:   Another allocated matrix object whose contents are same
  173.                 as A
  174. Example:
  175.                 MATRIX  A, B;
  176.  
  177.                 A = mat_creat( 5, 4, ZERO_MATRIX );
  178.  
  179.                 /*
  180.                 * B is also a 5 x 4 zero matrix now
  181.                 */
  182.                 B = mat_copy( A );
  183.                 ...
  184.                 mat_free( B );
  185.  
  186. See Also:       mat_colcopy1()
  187. -------------------------------------------------------------------------------
  188.  
  189.  
  190.  
  191.  
  192. ===============================================================================
  193. 3. BASIC MATRIX OBJECT INPUT/OUTPUT OPERATION
  194. ===============================================================================
  195. -------------------------------------------------------------------------------
  196. Function:       int fgetmat (MATRIX A, FILE * fp)
  197. Synopsis:       read a matrix from stream
  198. Parameter:      A: allocated matrix
  199.                 fp: a stream pointer obtained from fopen() or predefined
  200.                 pointer in standard library such as stdin
  201. Return Value:   number of matrix elements read
  202. Example:
  203.                 MATRIX  A;
  204.                 FILE    *fp;
  205.  
  206.                 A = mat_creat(3, 3, UNDEFINED);
  207.                 fp = fopen("mymatrix.dat", "r");
  208.                 fgetmat( A, fp );
  209.  
  210. See Also:       mat_dumpf(), mat_dump(), mat_fdump(), mat_fdumpf()
  211. -------------------------------------------------------------------------------
  212. Function:       MATRIX mat_dump   (MATRIX A)
  213.                 MATRIX mat_dumpf  (MATRIX A, char * format)
  214.                 MATRIX mat_fdump  (MATRIX A, FILE * fp)
  215.                 MATRIX mat_fdumpf (MATRIX A, char * format, FILE * fp)
  216.  
  217. Synopsis:       mat_dump:  dump a matrix to std output with default format
  218.                 mat_dumpf: dump a matrix to std output with specified format
  219.                 mat_fdump: dump a matrix to a file with default format
  220.                 mat_fdumpf:dump a matrix to a file with specified format
  221.  
  222. Parameter:      A: allocated matrix
  223.                 format: same as printf() 's format parameter, but can only
  224.                         be floating point type, such as "%.2f ", etc.
  225.                 fp: file pointer obtained via fopen()
  226.  
  227. Return Value:   matrix A
  228.  
  229. Example:
  230.                 MATRIX  A;
  231.  
  232.                 A = mat_creat( ... );
  233.                 ...
  234.                 /*
  235.                 * dump the matrix to standard output and each element
  236.                 * is restricted to 2 precision format
  237.                 */
  238.                 mat_dumpf( A, "%.2f ");
  239.  
  240. See Also:       fgetmat()
  241. -------------------------------------------------------------------------------
  242.  
  243.  
  244.  
  245.  
  246. ===============================================================================
  247. 4. BASIC MATRIX OBJECT MATHEMATICAL OPERATION
  248. ===============================================================================
  249. -------------------------------------------------------------------------------
  250. Function:       MATRIX mat_add (MATRIX A, MATRIX B);
  251.                 MATRIX mat_sub (MATRIX A, MATRIX B);
  252. Synopsis:       mat_add: addition of 2 matrices
  253.                 mat_sub: substraction of 2 matrices
  254. Parameter:      A, B: allocated matrices
  255. Return Value:   a newly allocated matrix which is the result of the operation
  256. Example:
  257.  
  258.                 MATRIX  A, B, C;
  259.  
  260.                 A = mat_creat( 5, 5, UNIT_MATRIX );
  261.                 B = mat_creat( 5, 5, UNIT_MATRIX );
  262.  
  263.                 C = mat_add( A, B );
  264.  
  265.                 mat_dump( C );
  266.  
  267.                 mat_free( A );
  268.                 mat_free( B );
  269.                 mat_free( C );
  270.  
  271. Note:           A, B must be of the same dimensions
  272. See Also:       mat_mul, mat_inv
  273. -------------------------------------------------------------------------------
  274. Function:       MATRIX mat_mul (MATRIX A, MATRIX B);
  275. Synopsis:       multiplication of 2 matrices
  276. Parameter:      A, B: allocated matrix
  277. Return Value:   a newly allocated matrix which is the result of the operation
  278. Example:
  279.                 MATRIX  A, B, C;
  280.  
  281.                 A = mat_creat( 5, 3, UNIT_MATRIX );
  282.                 B = mat_creat( 3, 6, UNIT_MATRIX );
  283.  
  284.                 /*
  285.                 *  C is now a 5 x 6 matrix
  286.                 */
  287.                 C = mat_add( A, B );
  288.  
  289.                 mat_dump( C );
  290.                 ...
  291.  
  292. Note:           the column dimension of A must equal row dimension of B
  293. See Also:       mat_add, mat_sub
  294. -------------------------------------------------------------------------------
  295. Function:       MATRIX mat_inv (MATRIX A)
  296. Synopsis:       find the inverse of a matrix
  297. Parameter:      A: allocated square matrix
  298. Return Value:   a newly allocated square matrix which is the inverse of A
  299. Example:
  300.                 MATRIX  A, AI;
  301.  
  302.                 /*
  303.                 * A must be a square matrix
  304.                 */
  305.                 A = mat_creat( 7, 7, UNIT_MATRIX );
  306.                 ...
  307.                 /*
  308.                 * find the inverse of A
  309.                 */
  310.                 AI = mat_inv( A );
  311.                 ...
  312.  
  313. See Also:       mat_tran, mat_add, mat_sub
  314. -------------------------------------------------------------------------------
  315. Function:       MATRIX  mat_tran( MATRIX A )
  316. Synopsis:       find the transpose of a matrix
  317. Parameter:      A: allocated matrix
  318. Return Value:   a newly allocated matrix which is the transpose of A
  319. Example:
  320.                 MATRIX  A, T;
  321.  
  322.                 A = mat_creat( 3, 5, UNDEFINED );
  323.                 ...
  324.                 T = mat_tran( A );
  325.                 ...
  326.  
  327. See Also:       mat_inv
  328. -------------------------------------------------------------------------------
  329.  
  330.  
  331.  
  332.  
  333. ===============================================================================
  334. 5. DETERMINANT OPERATIONS
  335. ===============================================================================
  336. -------------------------------------------------------------------------------
  337. Function:       MATRIX mat_submat (MATRIX A, int i, int j)
  338. Synopsis:       form a new matrix by deleting a row and a column of A
  339. Parameter:      A: allocated matrix
  340.                 i, j: row and column of A which will not appear in the
  341.                       resulting matrix
  342. Return Value:   a new matrix whose dimensions are 1 less than A
  343. Example:
  344.                 MATRIX  A, B
  345.  
  346.                 A = mat_creat( 3, 4, UNDEFINED );
  347.                 ...
  348.                 B = mat_submat( A, 2, 2 );
  349.                 /*
  350.                 *       suppose A =  [ 1 2 3 4 ]
  351.                 *                    [ 3 3 4 5 ]
  352.                 *                    [ 6 7 9 9 ]
  353.                 *
  354.                 *       then B =     [ 1 2 4 ]
  355.                 *                    [ 3 3 5 ]
  356.                 */
  357.  
  358. Note:           Do not be misled -- the contents in A will NOT be changed
  359. See Also:       mat_det, mat_cofact, mat_minor
  360. -------------------------------------------------------------------------------
  361. Function:       double mat_cofact (MATRIX A, int i, int j)
  362. Synopsis:       find out the cofactor of A(i,j)
  363. Parameter:      A: allocated square matrix
  364.                 i,j: row, column position of A for the cofactor
  365. Return Value:   the value of cofactor of A(i,j)
  366. Example:
  367.                 MATRIX  A;
  368.  
  369.                 A = mat_creat( 5, 5, UNIT_MATRIX );
  370.                 ...
  371.                 printf( "cofactor of A(0,2) = %f\n", mat_cofact( A, 0, 2 ));
  372.  
  373. See Also:       mat_det, mat_minor
  374. -------------------------------------------------------------------------------
  375. Function:       double mat_minor (MATRIX A, int i, int j)
  376. Synopsis:       find out the minor of A(i,j)
  377. Parameter:      A: allocated square matrix
  378.                 i,j: row, column position of A for the minor
  379. Return Value:   the value of minor of A(i,j)
  380. Example:
  381.                 MATRIX  A;
  382.  
  383.                 A = mat_creat( 5, 5, UNIT_MATRIX );
  384.                 ...
  385.                 printf( "minor of A(0,2) = %f\n", mat_minor( A, 0, 2 ));
  386.  
  387. See Also:       mat_det, mat_cofact
  388. -------------------------------------------------------------------------------
  389. Function:       double mat_det (MATRIX A)
  390. Synopsis:       find the determinant of a matrix
  391. Parameter:      A: allocated square matrix
  392. Return Value:   the determinant value of |A|
  393. Example:
  394.                 MATRIX  A;
  395.                 double  det;
  396.  
  397.                 A = mat_creat( 5, 5, UNIT_MATRIX );
  398.                 det = mat_det( A );
  399.  
  400. See Also:       mat_cofact, mat_minor, mat_submat
  401. -------------------------------------------------------------------------------
  402.  
  403.  
  404.  
  405.  
  406. ===============================================================================
  407. 6. ADVANCED MATRIX OBJECT MATHEMATICAL OPERATION
  408. ===============================================================================
  409. -------------------------------------------------------------------------------
  410. Function:       MATRIX mat_lsolve (MATRIX A, MATRIX B)
  411. Synopsis:       solve simultaneous linear equation AX = B given A, B
  412. Parameter:      A, B: allocated matrix
  413. Return Value:   newly allocated matrix X in AX = B
  414. Example:
  415.                 MATRIX  A, B, X;
  416.  
  417.                 A = mat_creat( 5, 5, UNDEFINED );
  418.                 fgetmat( A, stdin );
  419.                 ...
  420.                 B = mat_creat( 5, 1, UNDEFINED );
  421.                 fgetmat( B, stdin );
  422.                 ...
  423.                 X = mat_lsolve( A, B );
  424.                 mat_dump( X );
  425.  
  426. Note:           number of rows in A and B must be equal
  427. See Also:       mat_lsolve_durbin
  428. -------------------------------------------------------------------------------
  429. Function:       MATRIX mat_lsolve_durbin (MATRIX A, MATRIX B)
  430. Synopsis:       simultaneous linear equations wtih Levinson-Durbin method
  431. Parameter:      A, B: allocated matrix where A is an autocorrelated matrix and
  432.                       B is derived from A
  433.  
  434.                 A, B must be the following forms:
  435.  
  436.                 |  a0   a1   a2  .. an-1 | |  x1   |    |  a1   |
  437.                 |  a1   a0   a1  .. an-2 | |  x2   |    |  a2   |
  438.                 |  a2   a1   a0  .. an-3 | |  x3   |  = |  ..   |
  439.                 |  ...                   | |  ..   |    |  ..   |
  440.                 |  an-1 an-2 ..  .. a0   | |  xn   |    |  an   |
  441.  
  442.                 where A is a symmetric Toeplitz matrix and B
  443.                 in the above format (related to A)
  444.  
  445. Return Value:   a newly allocated matrix X which is the solution of AX = B
  446.  
  447. Example:        this method only applies to certain A, B only.
  448.                 e.g.
  449.  
  450.                 A =  [1 3 9]        B = [3]
  451.                      [3 1 3]            [9]
  452.                      [9 3 1]            [12]  <- the last one is unrelated to A
  453.  
  454. See Also:       mat_SymToeplz
  455. -------------------------------------------------------------------------------
  456. Function:       MATRIX mat_SymToeplz (MATRIX R);
  457. Synopsis:       create a symmetric Toeplitz matrix from a
  458.                 Autocorrelation vector
  459. Parameter:      R: allocated matrix of dimension n x 1
  460. Return Value:   a newly allocated symmetrical Toeplitz matrix
  461. Example:
  462.                 e.g.
  463.  
  464.                 MATRIX  A, R;
  465.  
  466.                 R = mat_creat( 3, 1, UNDEFINED );
  467.                 ...
  468.                 A = mat_SymToeplz( R );
  469.  
  470.                 /*
  471.                 *  if
  472.                 *
  473.                 *  R =  [1 3 9]         A =  [1 3 9]
  474.                 *                            [3 1 3]
  475.                 *                            [9 3 1]
  476.                 *
  477.                 */
  478.  
  479. See Also:       mat_lsolve_durbin
  480. -------------------------------------------------------------------------------
  481.